p.help

   1  p is a tool for managing patches.  It contains many
   2  subcommands.  To use a particular subcommand, give it
   3  as the first argument to p, and then give any arguments
   4  that subcommand requires
   5
   6 files
   7  p keeps all it's files and patches in a subdirectory of
   8  the toplevel directory of a project.  This subdirectory
   9  is called ".patches".  It is often convenient for
  10  ".patches" to actually be a symbolic link to somewhere
  11  else altogether.
  12
  13  The files and directories contained in .patches are:
  14    applied/    A directory containing applied patches
  15    removed/    A directory containing removed patches
  16    include/    A directory containing included patches
  17      Files in these directories are prefixed by a 3digit number
  18      which indicate thr order in which patches were added.
  19      The remainder of the filename is the name of the patch.
  20      Each file contains:
  21        Status: status
  22        ... notes ...
  23        ... diffstat output ...
  24        the actual patch
  25    name        A file containing the name of the current patch
  26    status      A file containing the status of the current patch
  27    notes       A file with notes about the patch
  28    patch       A a recently generated copy of the current patch
  29    files       A list of files that are 'checked out'
  30    to-resolve  A list of files that might have conflicts that need resolving
  31    tmp         A temporary file
  32    last-applied A most recently apply patch that had conflicts
  33    last-purge
  34    dest/       A directory where 'p publish' puts patch sets.
  35    SOURCE/     A directory where a bk repository lives.
  36    mail/       A directory of patches converted to email messages
  37    cc          A files listing:  prefix name emailaddr
  38                 When mailing patches which start with prefix, name
  39                 is put on the subject line, and the mail is cc:ed to
  40                 emailaddr
  41    maintainer  This is where patches are mailed to
  42    owner       These mail headers are included in each mail message
  43    get-version A script to get a base version number for use when publishing
  44    to-resolve  List of files have have outstanding conflicts to be resolved.
  45
  46
  47 model
  48 overview
  49  What is 'p' ?
  50
  51  'p' is a patch management system, not a source code control system.
  52  It allows you to create a set of patches against a base release, to
  53  annotate those patches with comments, and to revisit and edit patches
  54  after they have been committed.
  55
  56  It also allows you to update the base release that the patches are
  57  against, and then re-apply all patches.
  58
  59  At any time, there are a number of applied patches, a number of
  60  removed patches and possibly a current patch.
  61  The sets of applied and removed patches act much like stacks.  The current
  62  patch can be moved to the top of either (commit or discard), and the top
  63  of either patch can be moved to the current patch (open or apply).
  64  open and apply actualy allow any patch in the corresponding stack to be
  65  made current, and assume that the use won't re-order patches that
  66  should not be re-ordered.
  67
  68  To enable 'p' for a project, you simply create a directory called ".patches"
  69  in the top level directory of that project.  Files should be checked out
  70  ("p co filename") before editing but never need to be checked in.  Applying
  71  and external patch automatically checks out all modified files.
  72
  73  Often it is appropriate to have the .patches directory elsewhere (for
  74  example in an http-export directory tree for public access) and have a
  75  symlink from .patches to that location.
  76
  77  p can be run from any subdirectory of a project containing a .patches
  78  directory.
  79
  80  To find out about the contents of the .patches directory, see
  81       p help files
  82
  83  Some common commands are:
  84     p co filename               # monitor changes to filename
  85     p make                      # create and view the current patch
  86     p commit                    # commit the current patch
  87     p discard                   # discard current patch, saving it as
  88                                 # a removed patch
  89     p apply                     # re-apply a removed patch, or apply
  90                                 # an external patch
  91     p list                      # list current patches
  92
  93 co
  94  Usage:  p co filename
  95
  96  prepare filename for editing.  This makes sure there is a
  97  copy of the file with a ~current~ suffix, and that the file
  98  is listed in in .patches/files.  This command can be run from
  99  a subdirectory of the project, and it will still do the
 100  right thing.
 101
 102 make
 103 view
 104  Usage:  p make
 105          p view [patchnamefragment]
 106
 107  make and view provide the same functionality.
 108  When given a patch name fragment, they will allow the unique
 109  patch with that name (either applied or removed) to be viewed
 110  (using the pager $PAGER, or less).
 111  Without an argument, the current patch is calculated and
 112  displayed.  This explains the two names as with no argument,
 113  they both make, and view the current patch.
 114
 115 all
 116  Usage:  p all
 117
 118  Generate a composite patch of all currently applied patches.
 119  This involves creation a patch from the ~orig~ version of every
 120  file to it's current version.
 121
 122 status
 123 name
 124
 125  Usage: p status [newstatus]
 126         p name [newname]
 127
 128  If a new status or name is given, it is recorded as the current
 129  status or name for the current patch.  If no argument is given,
 130  the command will prompt for both a new name and a new status.
 131  The current value is offered as a default in each case.
 132
 133 note
 134 notes
 135  Usage: p notes
 136
 137  Open the notes describing the current patch in an $EDITOR
 138  The notes should contain a simple one-line description,
 139  a black line, and then a detailed description.
 140
 141 discard
 142  Usage: p discard
 143
 144  The current patch is discard: moved to the .patches/removed
 145  directory.  If it doesn't have a name or status, these are
 146  prompted for.
 147
 148 commit
 149  Usage: p commit
 150
 151  The current patch is commit: moved to the .patches/applied
 152  directory.  If name or status aren't set, these are prompted
 153  for.  If no notes have been written, and $EDITOR session is
 154  started with a template for some notes.
 155  The patch is presented in the file being edited for reference,
 156  but will be removed from the notes on exit.
 157
 158 open
 159  Usage: p open [last | patch-name-fragment]
 160
 161  The open command is used to open a previously commited
 162  patch for further editing.
 163
 164  Without any argument, a list of available commited patches
 165  is given.
 166  If the argument 'last'is given, then the most recently commited
 167  patch is opened.
 168  Otherwise a unique patch with a name containing the name fragment
 169  is openned.  If there is no such unique patch, and error message
 170  is given.
 171
 172 included
 173  Usage: p included [-f] [last | patch-name-fragment]
 174
 175  After updating the base release of a project, some of the patches
 176  which are currently "removed" may already have been included in that
 177  release and so don't need to be maintained any more.
 178
 179  The "included" command will check if a given patch appears to have
 180  been included and if so, moves it to the .patches/included directory.
 181  The test is performed by seeing if 'patch' is able to remove the
 182  patch.  If it cannot, but you are sure that the patch has been included
 183  (the problems patch reports are spurious) then using '-f' will cause
 184  the patch to be moved to 'included' anyway.
 185
 186 list
 187  Usage: p list
 188
 189  List all the patches in either 'applied' or 'removed'.
 190
 191 apply
 192  Usage: p apply [-f] [-a] [last | patch-name-fragment | filename]
 193
 194  This command is used for applying a patch to the project.
 195  If a patch in 'removed' is given, then it is moved out of 'removed'
 196  and is applied.  If a filename is given, the patch in that file is
 197  applied but the file is left unchanged.
 198
 199  When applying a patch, all affected files are checked-out first.
 200
 201  If 'patch' cannot apply the patch without error, 'apply' will fail.
 202  Giving the '-f' option will cause 'apply' to apply the patch anyway,
 203  and then run 'wiggle' to merge any rejected patch chunks as best
 204  as possible.  Any files for which wiggle finds unresolvaable conflicts
 205  while have its name saved in a file (.patches/to-resolve).  This
 206  list is used by the 'p resolve' command.
 207
 208  Normally, 'apply' will not apply a patch to be applies if there is
 209  one already open.  However the '-a' option may be given to ask
 210  'apply' to "append" the patch to the current patch.
 211
 212 resolve
 213  Usage: p resolve
 214
 215  This is used to resolve any conflicts found by wiggle.  Each file
 216  listed in .patches/to-resolve is presented for editing, and then
 217  has wiggle run over it again to check that all conflicts have
 218  been resolved.
 219
 220 publish
 221  Usage: p publish
 222
 223  The 'publish' command will create a new subdirectory of
 224     .patches/dest
 225  (which is often a symlink to a web-page area) and copy
 226  all current applied and removed patches into that directory.
 227  It also creates a complete patch (with "p all") and stores
 228  that in the directory.
 229
 230 clean
 231  Usage: p clean
 232
 233  clean checks that no patches are currently applied, and
 234  cleans up any ~current~ or ~orig~ files that have been left
 235  in the source tree.  It also removed write permission from
 236  all checked-out files.
 237
 238  It effectively undoes all check-outs.
 239
 240  It is run as part of 'update' which incorporates upstream
 241  changes into a source tree.
 242
 243 openall
 244  Usage: p openall
 245
 246  This command repeatedly runs "p open last && p discard" until
 247  that fails, which usually means that all patches have been
 248  discarded.  This is part of the preparation for incorporating
 249  upstream changes.
 250
 251 recommit
 252  Usage: p recommit patchname
 253
 254  This command will re-apply and re-commit removed patches
 255  that successfully apply until the names patch has been applied.
 256  Patches are applied in reverse order, which is consistant with
 257  the order in which they were removed.
 258
 259 snapshot
 260  Usage: p snapshot
 261
 262  This command takes a shapshot of the current patch so that further
 263  work can be done in the patch, but it can easily be removed if
 264  there are problems.
 265
 266  This might be used before appending a patch incase something goes
 267  wrong in the appending process.
 268
 269 snapdiff
 270  Usage: p snapdiff
 271
 272  Display the differences between the latest snapshot and the current
 273  source.
 274
 275 snapback
 276  Usage: p snapback
 277
 278  Revert all changes since the last snapshot
 279
 280 pull
 281  Usage: p pull
 282
 283  Update the local copy of the official source repository.  This
 284  can be found by following the .patches/SOURCE link.
 285
 286  Currently the code assumes it is a BitKeeper repository and
 287  runs "bk pull".  It should be enhanced to recognise CVS and
 288  run "cvs update".
 289
 290 update
 291  Usage: p update
 292
 293  This command updates the based release of the package.  To
 294  do this it removes all patches (p openall), cleans up (p clean),
 295  creates a patch from information in .patches/SOURCE, and applies
 296  that patch.  It currently makes no attempt to re-apply any
 297  patches, or to "p included" and patches.
 298
 299  Currently the code assumes a BitKeeper repository and uses
 300  "bk export -tpatch -rLASTEST," to extract a patch, and then
 301  retags the repository with "bk tag LATEST".  It should be
 302  enhanced to recognise and work with CVS as well.
 303
 304 premail
 305  Usage: p premail [patch-name-prefix]
 306
 307  This command converts a selection of patches to Email messages.
 308  The email messages are stored in .patches/mail.
 309  SAY MORE HERE
 310
 311 nomail
 312  Usage: p nomail
 313
 314  Remove the .patches/mail directory and contents.
 315
 316 email
 317  Usage: p email
 318
 319  Send all mail messages in .patches/mail.  On success, each
 320  email message is removed.
 321
 322 help
 323  Usage: p help [topic]
 324
 325  Print out help messages, which are contained in a file
 326    p.help
 327  in the same directory that p was run from.
 328  Without a topic, a general introduction and a list of topics
 329  is presented.  With a topic, help on that topic is presented.
 330
 331 purge
 332  Usage: p purge
 333
 334  Make copy of the current patch in .patches/last-purge (just
 335  in case) and then purge the current patch complete.